<TeXmacs|1.99.16>

<project|rehash.tm>

<style|tmmanual>

<\body>
  The introduction was a lie, this binding is (partly) event based!

  <subsection|Adding & removing callbacks>

  A download <todo|maybe also upload> can have a few callbacks attached, that
  are called e.g. for when a part is downloaded, or the download has
  completed. A callback does not have to be explicitely removed (although
  that is preferred), as callbacks are removed by garbage collection if their
  \<#2018\>tag\<#2019\> (which can be explicitely used to change or remove a
  callback) is unreachable.

  This automatical removal may be useful e.g. if the application
  \<#2018\>statistics\<#2019\> component mostly separate from the
  \<#2018\>real\<#2019\> download code and the statistics component crashes
  (due to some bug). Then the callback for statistics may be collected, along
  with now unreachable and potentially resource-heavy objects in the closure
  of this callback (e.g. various statistic tables). So it should be (resource
  utilisation-speaking) acceptable to keep the application active for a long
  time, and patch buggy code & restart after a crash.

  The same reason applies to automatical collection of download contexts, and
  handles to the FS service.

  These procedures may be called concurrently.

  <\explain>
    <scm|(add-progress-callback! <scm-arg|object>
    <scm-arg|cb>)><explain-synopsis|Add a progress callback>
  <|explain>
    Add a progress callback <var|cb> to some object <var|object>. An object
    of unspecified type is returned (called the \<#2018\>tag\<#2019\>), which
    can be used with <var|remove-progress-callback!> to remove the callback.
    When <var|object> is closed, <var|object> will drop it reference to
    <var|cb>.
  </explain>

  <\explain>
    <scm|(remove-progress-callback! <scm-arg|object>
    <scm-arg|tag>)><explain-synopsis|Remove a progress callback>
  <|explain>
    Remove a progress callback identified by the tag <var|tag> from the
    object <var|object>.

    <todo|maybe an exception if the callback doesn't exist anymore>
  </explain>

  <subsection|How is a callback called?>

  Callbacks are usually called from GNUnet context. As such, it is important
  to return quickly! The bindings also haven't got a clue what to do in case
  of an exception, so best don't throw any! <todo|log, but otherwise ignore
  exceptions in <scm|(rehash fibers)>>. A callback must be a <scm|lambda*>,
  accepting any number of keyword arguments. Currently, the following are
  defined:

  <\description>
    <item*|<scm|#:object>>the object at cause of this calling back

    <item*|<scm|#:pinfo>>an appropriate progress info structure (from
    <scm|(rehash fs progress-info)>)
  </description>
</body>

<\initial>
  <\collection>
    <associate|save-aux|false>
  </collection>
</initial>